package com.googlecode.ebasys.dao;

import java.util.List;

import org.springframework.transaction.annotation.Transactional;

import com.googlecode.ebasys.entity.PersistentEntity;

/**
 * Data Access Object intefrace for {@link PersistentEntity}
 * 
 * Implementation should be able to perform basic CRUD operations. Unsupported
 * operations should throw {@link UnsupportedOperationException}.
 *
 * @author Tomas Varaneckas
 * @version $Id: EntityDao.java 58 2009-01-22 20:49:29Z tomas.varaneckas $
 */
@Transactional
public interface EntityDao<T extends PersistentEntity> {
    
    /**
     * Finds one unique instance by it's Id
     * 
     * @param id
     * @return Instance or null if not found
     */
    public T findById(Long id);
    
    /**
     * Finds all existing instances
     * 
     * @return A list of all instances or an empty list if none were found
     */
    public List<T> findAll();
    
    /**
     * Finds a list of instances that match a given example
     * 
     * @param example Example instance
     * @return A list of matching instances or an empty list if none were 
     *         matching
     */
    public List<T> findByExample(T example);
    
    /**
     * Saves or updates the entity
     * 
     * @param entity New or existing entity
     * @return true on success, false on failure. Errors a briefly logged at
     *         WARN log level, strack traces at TRACE log level 
     */
    public boolean save(T entity);
    
    /**
     * Deletes entity by a given Id
     * 
     * @param id Id of entity to delete
     * @return true on success, false on failure. Errors a briefly logged at
     *         WARN log level, strack traces at TRACE log level 
     */
    public boolean deleteById(Long id);
}
